Skip to main content

JavaScript socketClient

What is the Corva JavaScript socketClient?​

Corva JavaScript socketClient is a software tool that allows setting up live data updates in your application.

socketClient scheme

How does that work?​

The JavaScript socketClient will try to establish a WebSocket connection with Corva Subscriptions Server and listen channel updates. Channel consists of a dataset name, provider, asset id (or company id for reference type datasets) and event type. Corva Subscriptions Server is monitoring datasets and fires three different types of events:

  1. 'update' - will fire in the case of when records are updated;
  2. 'destroy' - will fire in the case of when records are destroyed;
  3. ' ' (empty) - will fire in the case of when new records are created;

The subscribed app will be notified about each update from the subscribed channel.

Signature example:

import { socketClient } from '@corva/ui/clients';

const subscription = {
  provider: 'corva', // dataset provider. Type:string (required)
  dataset: 'wits', // dataset name. Type: string (required)
  assetId: 123, // asset id (well.asset_id). Type: number (required for time and depth based datasets)
  companyId: 123, // company id. Type: number. (required ONLY for reference type datasets)
  event: '', // event type. Type: string. (optional, empty by default)
};

const options = {
  onDataReceive: event => console.log(event), // function invoked on each event. (optional)
};

// unsubscribe - Function which unsubscribes the app from  subscription updates
const unsubscribe = socketClient.subscribe(subscription, options);

Usage example with React Hooks:

/*
   This example shows the very basic live data subscription usage.
   App subscribes to wits stream and displays records as time - hole depth items
*/
import { useState, useEffect } from 'react';
import { socketClient } from '@corva/ui/clients';

function App(props) {
  // NOTE: Read asset_id from well. Most datasets are indexed by asset_id.
  const {
    well: { asset_id: assetId },
  } = props;
  // NOTE: Define state to store subscription data
  const [witsData, setWITSData] = useState([]);

  useEffect(() => {
    setWITSData([]); // NOTE: Clean old state. Needed when assetId changed

    const subscription = { provider: 'corva', dataset: 'wits', assetId }; // Subscription params
    const onDataReceive = event =>
      setWITSData(prevData => prevData.concat(event.data)); // Concatenate new records to state

    const unsubscribe = socketClient.subscribe(subscription, { onDataReceive });

    // NOTE: Unsubscribe to prevent memory leaks in your app
    return () => unsubscribe();
  }, [assetId]);

  return (
    <div>
      <ul>
        {witsData.map(({ timestamp, data: { hole_depth } }) => {
          const date = new Date(timestamp * 1000);
          const formattedDate = date.toTimeString().slice(0, 8);
          return (
            <li key={timestamp}>
              Time: {formattedDate} - Hole Depth: {hole_depth}
            </li>
          );
        })}
      </ul>
    </div>
  );
}

export default App;

Note: Unsubscribe is important. Make sure you unsubscribed from all subscriptions when app is unmounted. That will help avoid data leaks.

When to use socketClient?​

Most common case is to update charts in your app in real-time. Without socket subscriptions, users would need to refresh a page in their browsers to see the most recent data in their apps.

Examples:

  • Consider a case when your app shows wells hole depth in real time. App should just subscribe to wits dataset, take the very latest record and render it's hole depth.
  • Consider a case when your app has a chart which shows some historical data and should be updated in real time. Then you would need to fetch the initial data through HTTP request (using corvaDataAPI or corvaAPI) and subscribe to dataset updates. In onDataReceived callback you should add new records to your app state, it will make your chart update in real time.
  • Consider a case when your app shows table with well sections and you need to keep it up to date. Then you might need to subscribe to data.well-sections dataset with event type update. This will make your table reflect to existing well sections changes.

When NOT to use socketClient?​

  • When your app shows data that is not getting updates frequently. For example, if your data changes once per day, then live data subscription may be not needed.
  • When user goes back in time with well timeline, then usually only the historical data for that period is shown.

Code examples:​